home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / ulog / RCS / Ulog.man,v < prev    next >
Encoding:
Text File  |  1988-12-31  |  5.5 KB  |  161 lines
  1. head     1.1;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.1
  10. date     88.12.30.16.20.46;  author ouster;  state Exp;
  11. branches ;
  12. next     ;
  13.  
  14.  
  15. desc
  16. @@
  17.  
  18.  
  19.  
  20. 1.1
  21. log
  22. @Initial revision
  23. @
  24. text
  25. @'\" $Header: Ulog,v 1.1 88/09/22 22:07:24 douglis Exp $ SPRITE (Berkeley)
  26. .so \*(]ltmac.sprite
  27. .HS Ulog lib
  28. .BS
  29. .SH NAME
  30. Ulog \- obtain or update information in the database of user logins and logouts.
  31. .SH SYNOPSIS
  32. .nf
  33. \fB#include    <ulog.h>\fR
  34.  
  35. Ulog_Data *
  36. \fBUlog_LastLogin\fR(\fIuid\fP)
  37.  
  38. int
  39. \fBUlog_GetAllLogins\fR(\fInumEntries, locPtr, dataArray\fP)
  40.  
  41. int
  42. \fBUlog_RecordLogin\fR(\fIuid, location, portID\fP)
  43.  
  44. int
  45. \fBUlog_RecordLogout\fR(\fIuid, portID\fP)
  46.  
  47. int
  48. \fBUlog_ClearLogins\fR()
  49.  
  50. .SH ARGUMENTS
  51.  
  52. .AS Ulog_Data dataArray[] 
  53. .AP int uid in
  54. A numerical identifier for a user for whom to retrieve or update information.
  55. .AP int numEntries in
  56. The number of Ulog_Data structures contained in \fIdataArray\fP.
  57. .AP int *locPtr in/out
  58. A pointer to an integer specifying the index of the next record in
  59. the user log to access.  
  60. .AP Ulog_Data dataArray[] out
  61. A buffer to hold Ulog_Data entries returned by the Ulog_GetAllLogins routine.
  62. .AP char *location in
  63. String specifying location of user logging in (i.e., remote host)
  64. .AP int portID in
  65. Numerical identifier for login port.
  66. .BE
  67. .SH DESCRIPTION
  68. The ulog library provides a facility to record logins and logouts in
  69. the system, to retrieve information about the last time a user
  70. logged in or about 
  71. all users logged into the system, and to clear the login entries for a
  72. host.  Each host has a fixed number of 
  73. entries allocated to it in the user log
  74. database file.  One entry, with a \fIportID\fP of
  75. \fBULOG_LOC_CONSOLE\fP, is reserved for the console of a host; there
  76. are (\fBULOG_MAX_PORTS\fP - 1) other
  77. entries available for rlogin processes.  (There is currently no
  78. facility for multiple local logins, such as over a serial line.)
  79. .PP
  80. The \fIulog\fP library converts between the ASCII representation stored in the
  81. database and an internal C structure, known as a Ulog_Data structure.
  82. This structure contains information giving <uid,hostID,portID>
  83. corresponding to a user logged in on a particular ``port'' on a
  84. particular host.  Each login entry also includes the time of the
  85. login, which is the \fBtv_sec\fP part of a \fBtime\fP structure.  It
  86. also includes any additional information for the location of the user;
  87. this is an arbitrary string that typically gives the host from which
  88. an rlogin occurs.
  89. Two database files are used: one for logins on a host/port basis, and
  90. one for the last login by each user.
  91. .PP
  92. A Ulog_Data structure is defined as follows:
  93. .DS L
  94. .ta 4n 2.5c 6.5c
  95. \fBtypedef struct\fR {
  96.     \fBint\fP \fIuid\fP;        /* user identifier */
  97.     \fBint\fP \fIhostID\fP;        /* host for which data is
  98.                        valid */
  99.     \fBint\fP \fIportID\fP;        /* port within host */
  100.     \fBint\fP \fIupdated\fP;    /* login time (in seconds since
  101.                        1/1/70); 0 if invalid */
  102.     \fBchar\fP \fIlocation\fP[\fBULOG_LOC_LENGTH\fP];
  103.                     /* location of user */
  104. } Ulog_Data;
  105. .DE
  106. .PP
  107. The \fBUlog_LastLogin()\fR procedure returns a pointer to a
  108. statically-allocated Ulog_Data structure.  Therefore, the contents of the
  109. structure may change on subsequent calls to \fBUlog_LastLogin()\fR.  The
  110. information returned by \fBUlog_LastLogin()\fR corresponds to the most
  111. recent login by the user specified by \fIuid\fP.
  112. .PP
  113. \fBUlog_GetAllLogins()\fR provides a mechanism for retrieving multiple login
  114. entries at once.  The user must allocate an array of Ulog_Data
  115. structures, and pass the size of the array and a pointer to it as
  116. arguments to \fBUlog_GetAllLogins()\fR.  In addition, the \fIlocPtr\fP
  117. argument specifies where in the login database to start looking.
  118. \fI*locPtr\fP 
  119. should be initialized to 0 prior to the first call to
  120. \fBUlog_GetAllLogins()\fR.  \fBUlog_GetAllLogins()\fR returns the number of
  121. entries in \fIdataArray\fP that were filled.  If that number is less
  122. than the maximum number specified by \fInumEntries\fP, then all data
  123. has been returned.  If it is equal to \fInumEntries\fP, then
  124. \fBUlog_GetAllLogins()\fR should be called again to retrieve additional
  125. entries from  the point at which the last call left off (given by
  126. \fI*locPtr\fP). 
  127. .PP
  128. \fBUlog_RecordLogin()\fR allows the caller to register information
  129. for a new login.  The caller specifies the user ID, location, and port
  130. of the user logging in.  The procedure obtains the hostID and current
  131. time, and records the login.
  132. .PP
  133. \fBUlog_RecordLogout()\fR provides a similar facility to record logouts.  It
  134. takes a user ID and port number, and it removes the corresponding
  135. loginn from the list
  136. of active logins.
  137. .PP
  138. \fBUlog_ClearLogins()\fR may be used at boot time to clear any old entries
  139. in the user log for the current host.  Note: if a host is down, it may
  140. still have entries in the user log.  It is the responsibility of the
  141. user to use the migration information database to determine if a host
  142. is up, in order to validate user log entries.
  143. .SH DIAGNOSTICS
  144. \fBUlog_RecordLogin()\fR, \fBUlog_RecordLogout()\fR, and \fBUlog_ClearLogins()\fR return zero if
  145. all went well.  Otherwise 
  146. they return -1 and the \fIerrno\fR variable contains additional information
  147. about what error occurred.  \fBUlog_GetAllLogins()\fR similarly returns -1 on
  148. error, but it returns 0 if no more records are available.  \fBUlog_LastLogin()\fR
  149. returns
  150. NULL on error. 
  151. .SH FILES
  152. .IP /sprite/admin/data/userLog
  153. The database of current logins on each host.
  154. .IP /sprite/admin/data/lastLog
  155. The database of each user's most recent login.
  156. .SH KEYWORDS
  157. user log, user ID, sprite ID
  158. .SH SEE ALSO
  159. db, mig, Mig_GetInfo, login, rlogin, rlogind
  160. @
  161.